flowchart TB
    classDef pr66 fill:#e6f7ff,stroke:#1890ff,color:#000
    classDef pr67 fill:#fff7e6,stroke:#fa8c16,color:#000
    classDef redis fill:#fff1f0,stroke:#cf1322,color:#000
    classDef disk fill:#f6ffed,stroke:#52c41a,color:#000

    subgraph L1["PATCH handler (PR #11767)"]
        REQ["request.content"]:::pr67
        ADP["TusChunkUploadStreamReader"]:::pr67
        HND["tus_upload_part"]:::pr67
        REQ --> ADP --> HND
    end

    subgraph L2["Upload engine (PR #11766)"]
        WTC["write_temp_chunk"]:::pr66
        CC["commit_chunk"]:::pr66
        FIN["assemble + cleanup"]:::pr66
    end

    subgraph L3R["Valkey · source of truth"]
        STATE["tus.upload.session:id"]:::redis
        LOCK["tus.upload.lock:id"]:::redis
    end

    subgraph L3F["shared FS · chunk payloads"]
        TMP["chunk_off.tok.tmp"]:::disk
        DAT["chunk_off.dat"]:::disk
        OUT["assembled file"]:::disk
    end

    HND -->|"1. drain body"| WTC
    HND -->|"2. promote temp"| CC
    HND -->|"3. on final commit"| FIN
    WTC -->|"lock-free write"| TMP
    CC -->|"acquire"| LOCK
    CC -->|"get / set"| STATE
    CC -->|"atomic rename"| DAT
    FIN -->|"concat in order"| OUT
    FIN -->|"mark COMPLETED"| STATE
    FIN -->|"unlink chunks"| DAT

classDiagram
    class TusUploadSession {
        +ensure_initialized()
        +read_state() TusSessionState
        +open_temp_chunk(offset) Path
        +write_temp_chunk(offset, reader) WrittenChunk
        +commit_chunk(offset, path, length, sha256) ChunkCommitResult
        +assemble(target)
        +cleanup()
    }
    class TusSessionState {
        +session_id
        +total_size
        +committed_chunks : ChunkMetadata[]
        +status : UploadStatus
        +committed_offset
        +find_at_offset(offset)
        +append_chunk(chunk)
    }
    class ChunkMetadata {
        +offset
        +length
        +sha256
    }
    class WrittenChunk {
        +path
        +length
        +sha256
    }
    class ChunkCommitResult {
        +state : TusSessionState
        +committed : bool
        +is_final_commit : bool
    }
    class TusUploadSessionArgs {
        +session_dir
        +session_id
        +total_size
        +valkey_client : ValkeyTusClient
        +lock_factory : DistributedLockFactory
    }
    TusSessionState o-- ChunkMetadata
    TusUploadSession ..> TusSessionState
    TusUploadSession ..> ChunkCommitResult
    TusUploadSession ..> WrittenChunk
    TusUploadSession ..> TusUploadSessionArgs

sequenceDiagram
    autonumber
    participant H as tus_upload_part
    participant S as TusUploadSession
    participant V as Valkey
    participant D as shared FS

    H->>S: ensure_initialized()
    S->>V: acquire lock + SET state if missing
    H->>S: write_temp_chunk(offset, reader)
    loop async for chunk in reader.read()
        S->>D: write chunk_off.tok.tmp (lock-free) + sha256
    end
    S-->>H: WrittenChunk(path, length, sha256)
    H->>S: commit_chunk(offset, path, length, sha256)
    Note over S,V: distributed lock window (short)
    alt status == COMPLETED
        S-->>H: no-op (late duplicate from another replica)
    else duplicate (same offset, length, sha256)
        S-->>H: committed=False (idempotent)
    else conflict (same offset, different content)
        S-->>H: ChunkConflictError 409
    else new chunk
        S->>D: atomic rename tmp to chunk_off.dat
        S->>V: update TusSessionState with new record
        S-->>H: ChunkCommitResult(is_final_commit?)
    end
    opt is_final_commit
        H->>S: assemble(target)
        S->>D: concat chunks in offset order
        S->>V: mark status=COMPLETED
        H->>S: cleanup()
        S->>D: unlink chunk files (state kept for TTL)
    end
    H-->>H: 204 No Content